============================================================
README for : Solving the vibrational Schrödinger equation
             with artificial neural networks
============================================================

0. OVERVIEW
------------------------------------------------------------
This folder contains the programs and input files for 
calculating the vibrational energies of methane and propane 
based on the trained neural network (NN) wave functions 
provided here. The calculation involves the following four 
steps:
1. Run mc_sampling.py to perform configuration sampling 
   based on the probability density of the wave function, 
   generating a sample dataset (e.g., data_x.bin).
2. Use the potential energy surface program to calculate 
   the potential energy values (e.g., data_v.bin) 
   corresponding to the configurations in data_x.bin.
3. Use the script wf_local_energy_on_nnpsi.py to calculate 
   the local energies for the sample dataset (e.g., 
   data_x.bin). From these local energies, the average 
   energy of the wave function and its standard deviation 
   can be obtained.
4. The energy levels of vibrational states are obtained by 
   averaging the average energies of all replicated wave 
   functions.

1. FILE STRUCTURE AND DESCRIPTION
------------------------------------------------------------
.
├── readme.txt
├── methane.json5                                            # Molecular Information stored in json5 formt file
├── propane.json5
├── mc_parameters-methane.json5                              # Example configuration file (json5 format) for MC parameters
├── mc_parameters-propane.json5
├── nnpsi.py                                                 # Neural-network wavefunction architecture module (python code)
├── energy.py                                                # Local energy module (python code)
├── mc_sampling.py                                           # Monte-Carlo Sampling (python code)
├── wf_local_energy_on_nnpsi.py                              # Program for computing the mean and standard deviation of the local energy (python code)
├── run-mc_methane.sh                                        # Example scrip for samping 
├── run-mc_propane.sh
├── run-methane.sh                                           # Example scrip for computing the mean and standard deviation of the local energy
├── run-propane.sh
├── LICENSE.txt
├── methane                                                  # Data files related to methane
│   ├── equilibrium_configuration_of_methane.xyz             # Equilibrium configuration of methan
│   ├── 0000                                                 # <vibration_state_dir>
│   │   ├── nn-parameters-0.pt                               # Parameters of neural-network wavefunction (PyTorch files)
│   │   └── ...                                              # Parameters of other replications
│   ├── ...                                                  # Other vibration states
│   └── PES                                                  # Potential energy surface program
│       ├── ch4pot.read
│       ├── Makefile
│       └── src
│           ├── callschwenke.f90
│           ├── ch4pes.f90
│           └── ch4pot_fast.f
└── propane                                                  # Data files related to propane. The subdirectory structure is the same as that of "./methane".
    ├── equilibrium_configuration_of_propane.xyz
    ├── ccc-asymm-stretch
    │   ├── data_v.bin
    │   ├── data_x.bin
    │   ├── nn-parameters-0.pt
    │   └── ...
    ├── ...
    └── PES
        ├── C3H8net.1
        ├── Makefile
        └── src
            ├── cross_product.f90
            ├── ff_C3H8.f90
            ├── fi_C3H8.f90
            ├── pes_C3H8.f90
            └── pes_tot.f90

2. SOFTWARE DEPENDENCIES
------------------------------------------------------------
- Python 3.9+
- Packages and version
    numpy       1.23.3
    torch       1.13.0
    json5       0.9.6

3. USAGE INSTRUCTIONS
------------------------------------------------------------
   3.1 The script "wf_local_energy_on_nnpsi.py" can be used to
compute the average and standard deviation of the local
energy for a specified dataset (e.g., data_x.bin,
data_v.bin). When executing "wf_local_energy_on_nnpsi.py
", specify the following file paths via command-line
arguments: molecular configuration coordinate data file
<coordinates_data>, potential energy data file
<potential_energy_data>, molecular information file
<molecular_information>, and neural network wavefunction
parameter file <nn_parameters>. And, you can limit the
maximum memory consumption by adjusting the variable
MAX_BATCH_SIZE (default value: int(1e5)) in
"wf_local_energy_on_nnpsi.py". Two example scripts
(./run-methane.sh and ./run-propane.sh) are also provided.

Command example:
$ python wf_local_energy_on_nnpsi.py \
  <coordinates_data> \
  <potential_energy_data> \
  <molecular_information> \
  <nn_parameters>

  3.2 The script "mc_sampling.py" can be used to perfoming
MC configuration samping in Cartesian coordination space
besed on the square of neural-network wavefunction. It will
print out the proposed configuration acceptance rate after
samping is completed. When using "mc_sampling.py", the
following file paths need to be specified via command-line
arguments: MC sampling parameters file <mc_cfg>, initial
molecular configuration file <x0_file>, neural network
wavefunction parameter file <nn_parameters> and the path to
save Cartesian coordinates for sampled configurations
<save_path>. There are also two example scripts
(./run-run-mc_methane.sh and ./run-mc_propane.sh).

Command example:
$ python mc_sampling.py <mc_cfg> <x0_file> <nn_parameters> \
  <save_path>

4. DATA DESCRIPTION
------------------------------------------------------------
An example dataset of methane and propane configurations 
(data_x.bin) and the potential energy (data_v.bin) can be 
found at the URL 
https://github.com/ms123234/nn_wavefunction/releases.

  4.1 The configuration dataset data_x.bin is obtained 
through MC sampling in Cartesian coordinate space. Its 
probability density function corresponds to the squared
wavefunction with parameters from
<vibration_state_dir>/nn-parameters-0.pt.

  4.2 The file data_v.bin contains potential energy values 
corresponding to the configurations in data_x.bin.

5. CONTACT
------------------------------------------------------------
Author : Shuaishuai Zhao & Dong H. Zhang*
E-mail : zhangdh@dicp.ac.cn

6. LICENSE
------------------------------------------------------------
This software is released under the MIT License.
The full text is available in the LICENSE.txt file.

